创建 Git 子仓库
目标： 在 A 项目中创建 B 项目，并将 B 项目作为独立仓库，通过 git submodule 的方式引入到 A 项目中。
一、为什么使用子仓库（submodule）
使用 git submodule 的核心原因是：
- B 项目可以独立开发、独立发布
- A 项目只引用 B 的某个确定版本
- 多个项目可以复用同一个 B
- 避免把所有代码都塞进一个仓库（假 monorepo）
适合场景：
- SDK / 工具库
- 基础组件
- 需要独立 CI / release 的模块
二、整体流程概览
- 在 A 项目中创建 B 项目目录
- 初始化 B 项目为独立 Git 仓库
- 使用
gh创建远程仓库并推送 - 将 B 项目作为 submodule 添加回 A 项目
- 提交 A 项目的 submodule 变更
三、在 A 项目中创建 B 项目
进入 A 项目根目录：
cd A-project
创建 B 项目目录（示例）：
mkdir -p packages/B-project
cd packages/B-project
四、初始化 B 项目仓库
1. 初始化 Git
git init
2. 创建初始提交（必须）
echo "# B-project" > README.md
git add .
git commit -m "chore: initial commit"
⚠️ submodule 不能引用一个没有 commit 的仓库
五、使用 GitHub CLI 创建远程仓库
确保已登录 GitHub：
gh auth status
创建并推送仓库（fish / bash 通用写法）：
gh repo create B-project --private --source=. --remote=origin --push
如果是 public 仓库，将
--private改为--public
验证远程仓库：
git remote -v
六、将 B 项目作为子仓库加入 A 项目
1. 回到 A 项目根目录
cd ../../
2. 删除本地 B 目录（关键步骤）
rm -rf packages/B-project
⚠️ submodule 会自行 clone 仓库，本地目录必须为空
3. 添加 submodule
git submodule add https://github.com/<用户名或组织>/B-project.git packages/B-project
成功后会生成：
packages/B-project/.gitmodules
七、提交 A 项目的 submodule 变更
git add .gitmodules packages/B-project
git commit -m "chore: add B-project as submodule"
git push
八、日常开发与更新流程
1. 开发 B 项目
cd packages/B-project
git checkout main
修改并提交：
git add .
git commit -m "feat: xxx"
git push
2. 在 A 项目中更新子仓库版本
cd ../../
git status
会看到：
modified: packages/B-project (new commits)
提交更新：
git add packages/B-project
git commit -m "chore: bump B-project submodule"
git push
九、Clone 含 submodule 的项目
推荐方式（一次性）
git clone --recurse-submodules <A-project-repo>
已 clone 项目补拉子仓库
git submodule update --init --recursive
十、常见坑总结
❌ 忘记给 B 项目做初始 commit
→ submodule 无法添加
❌ 没删除本地目录就 add submodule
→ already exists and is not a git repository
❌ 更新了 B，却没提交 A 的 submodule 指针
→ 其他人拉不到最新版本
十一、补充建议
- 统一子仓库放在
packages/或libs/目录 - submodule 更新必须有单独 commit
- 团队中约定：禁止直接修改 submodule 的 detached HEAD
结论： submodule 管理的是“依赖的提交”，不是代码本身。 想清楚“谁负责发布，谁负责引用”，就不会踩坑。
如果你愿意，我也可以帮你把这篇笔记改成：
- 团队规范版
- README 精简版
- 带流程图的版本